
<!DOCTYPE html>

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

    <title>Configuring user authentication &#8212; LAVA 2024.05 documentation</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="_static/bootstrap-sphinx.css" />
    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
    <script src="_static/doctools.js"></script>
    <script src="_static/sphinx_highlight.js"></script>
    <link rel="shortcut icon" href="_static/favicon.ico"/>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Adding your first devices" href="first-devices.html" />
    <link rel="prev" title="Installing on a Debian system" href="installing_on_debian.html" />
    <link rel="canonical" href="https://docs.lavasoftware.org/lava/authentication.html" />
  
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">
<script type="text/javascript" src="_static/js/jquery-1.12.4.min.js"></script>
<script type="text/javascript" src="_static/js/jquery-fix.js"></script>
<script type="text/javascript" src="_static/bootstrap-3.4.1/js/bootstrap.min.js"></script>
<script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>


  </head><body>

  <div id="navbar" class="navbar navbar-default navbar-fixed-top">
    <div class="container">
      <div class="navbar-header">
        <!-- .btn-navbar is used as the toggle for collapsed navbar content -->
        <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
        </button>
        <a class="navbar-brand" href="index.html"><span><img src="_static/lava.png"></span>
          LAVA</a>
        <span class="navbar-text navbar-version pull-left"><b>2024.05</b></span>
      </div>

        <div class="collapse navbar-collapse nav-collapse">
          <ul class="nav navbar-nav">
            
                <li><a href="genindex.html">Index</a></li>
                <li><a href="contents.html">Contents</a></li>
            
            
              <li class="dropdown globaltoc-container">
  <a role="button"
     id="dLabelGlobalToc"
     data-toggle="dropdown"
     data-target="#"
     href="index.html">Site <b class="caret"></b></a>
  <ul class="dropdown-menu globaltoc"
      role="menu"
      aria-labelledby="dLabelGlobalToc"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="index.html">Introduction to LAVA</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="contents.html">Contents</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary of terms</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="support.html">Getting support</a></li>
</ul>
</ul>
</li>
              
                <li class="dropdown">
  <a role="button"
     id="dLabelLocalToc"
     data-toggle="dropdown"
     data-target="#"
     href="#">Page <b class="caret"></b></a>
  <ul class="dropdown-menu localtoc"
      role="menu"
      aria-labelledby="dLabelLocalToc"><ul>
<li><a class="reference internal" href="#">Configuring user authentication</a><ul>
<li><a class="reference internal" href="#using-lightweight-directory-access-protocol-ldap">Using Lightweight Directory Access Protocol (LDAP)</a></li>
<li><a class="reference internal" href="#using-external-authentication-provider-supported-by-django-allauth">Using external authentication provider supported by django-allauth</a></li>
<li><a class="reference internal" href="#using-open-id-connect-oidc-authentication-providers">Using Open ID Connect (OIDC) authentication providers</a></li>
</ul>
</li>
</ul>
</ul>
</li>
              
            
            
              
                
  <li>
    <a href="installing_on_debian.html" title="Previous Chapter: Installing on a Debian system"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">&laquo; Installing on...</span>
    </a>
  </li>
  <li>
    <a href="first-devices.html" title="Next Chapter: Adding your first devices"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">Adding your f... &raquo;</span>
    </a>
  </li>
              
            
            
            
            
              <li class="hidden-sm"></li>
            
          </ul>

          
            
<form class="navbar-form navbar-right" action="search.html" method="get">
 <div class="form-group">
  <input type="text" name="q" class="form-control" placeholder="Search" />
 </div>
  <input type="hidden" name="check_keywords" value="yes" />
  <input type="hidden" name="area" value="default" />
</form>
          
        </div>
    </div>
  </div>

<div class="container">
  <div class="row">
    <div class="body col-md-12 content" role="main">
      
  <section id="configuring-user-authentication">
<span id="user-authentication"></span><span id="index-0"></span><h1>Configuring user authentication<a class="headerlink" href="#configuring-user-authentication" title="Permalink to this heading">¶</a></h1>
<p>The LAVA frontend is developed using the <a class="reference external" href="https://www.djangoproject.com/">Django</a> web application framework and
user authentication and authorization is based on the standard <a class="reference external" href="https://docs.djangoproject.com/en/3.2/topics/auth/">Django auth
subsystems</a>. This means that it is fairly easy to integrate authentication
against any source for which a Django backend exists. Discussed below are the
tested and supported authentication methods for LAVA.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>LAVA used to include support for OpenID authentication (prior to
version 2016.8), but this support had to be <strong>removed</strong> when incompatible
changes in Django (version 1.8) caused it to break.</p>
</div>
<p>Local Django user accounts are supported. When using local Django user
accounts, new user accounts need to be created by Django admin prior to use.</p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="simple-admin.html#admin-adding-users"><span class="std std-ref">Adding users and groups</span></a></p>
</div>
<section id="using-lightweight-directory-access-protocol-ldap">
<span id="ldap-authentication"></span><h2>Using Lightweight Directory Access Protocol (LDAP)<a class="headerlink" href="#using-lightweight-directory-access-protocol-ldap" title="Permalink to this heading">¶</a></h2>
<p>LAVA server may be configured to authenticate via Lightweight
Directory Access Protocol (LDAP). LAVA uses the <a class="reference external" href="https://django-auth-ldap.readthedocs.io/en/latest/">django_auth_ldap</a>
backend for LDAP authentication.</p>
<p>LDAP server support is configured using the following parameters in
<code class="docutils literal notranslate"><span class="pre">/etc/lava-server/settings.conf</span></code> (JSON syntax):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">&quot;AUTH_LDAP_SERVER_URI&quot;</span><span class="p">:</span> <span class="s2">&quot;ldap://ldap.example.com&quot;</span><span class="p">,</span>
<span class="s2">&quot;AUTH_LDAP_BIND_DN&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="s2">&quot;AUTH_LDAP_BIND_PASSWORD&quot;</span><span class="p">:</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
<span class="s2">&quot;AUTH_LDAP_USER_DN_TEMPLATE&quot;</span><span class="p">:</span> <span class="s2">&quot;uid=</span><span class="si">%(user)s</span><span class="s2">,ou=users,dc=example,dc=com&quot;</span><span class="p">,</span>
<span class="s2">&quot;AUTH_LDAP_USER_ATTR_MAP&quot;</span><span class="p">:</span> <span class="p">{</span>
  <span class="s2">&quot;first_name&quot;</span><span class="p">:</span> <span class="s2">&quot;givenName&quot;</span><span class="p">,</span>
  <span class="s2">&quot;email&quot;</span><span class="p">:</span> <span class="s2">&quot;mail&quot;</span>
<span class="p">},</span>
</pre></div>
</div>
<p>Use the following parameter to configure a custom LDAP login page
message:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">&quot;LOGIN_MESSAGE_LDAP&quot;</span><span class="p">:</span> <span class="s2">&quot;If your Linaro email is first.second@linaro.org then use first.second as your username&quot;</span>
</pre></div>
</div>
<p>Other supported parameters are:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">&quot;AUTH_LDAP_GROUP_SEARCH&quot;</span><span class="p">:</span> <span class="s2">&quot;LDAPSearch(&#39;ou=groups,dc=example,dc=com&#39;, ldap.SCOPE_SUBTREE, &#39;(objectClass=groupOfNames)&#39;&quot;</span><span class="p">,</span>
<span class="s2">&quot;AUTH_LDAP_USER_FLAGS_BY_GROUP&quot;</span><span class="p">:</span> <span class="p">{</span>
  <span class="s2">&quot;is_active&quot;</span><span class="p">:</span> <span class="s2">&quot;cn=active,ou=django,ou=groups,dc=example,dc=com&quot;</span><span class="p">,</span>
  <span class="s2">&quot;is_staff&quot;</span><span class="p">:</span> <span class="s2">&quot;cn=staff,ou=django,ou=groups,dc=example,dc=com&quot;</span><span class="p">,</span>
  <span class="s2">&quot;is_superuser&quot;</span><span class="p">:</span> <span class="s2">&quot;cn=superuser,ou=django,ou=groups,dc=example,dc=com&quot;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Similarly:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">&quot;AUTH_LDAP_USER_SEARCH&quot;</span><span class="p">:</span> <span class="s2">&quot;LDAPSearch(&#39;o=base&#39;, ldap.SCOPE_SUBTREE, &#39;(uid=</span><span class="si">%(user)s</span><span class="s2">)&#39;)&quot;</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If you need to make deeper changes that don’t fit into the
exposed configuration, it is quite simple to tweak things in
the code here. Edit
<code class="docutils literal notranslate"><span class="pre">/usr/lib/python3/dist-packages/lava_server/settings/common.py</span></code></p>
</div>
<p>Restart the <code class="docutils literal notranslate"><span class="pre">lava-server</span></code> and <code class="docutils literal notranslate"><span class="pre">apache2</span></code> services after any
changes.</p>
</section>
<section id="using-external-authentication-provider-supported-by-django-allauth">
<h2>Using external authentication provider supported by django-allauth<a class="headerlink" href="#using-external-authentication-provider-supported-by-django-allauth" title="Permalink to this heading">¶</a></h2>
<p>LAVA server can delegate its authentication using the <a class="reference external" href="https://django-allauth.readthedocs.io/en/latest/">django_allauth</a>
authentication backend.</p>
<p>To enable external provider authentication support you need to set
<cite>AUTH_SOCIALACCOUNT</cite> in your LAVA configuration. Do this by placing a config
snippet in yaml format in the directory <code class="docutils literal notranslate"><span class="pre">/etc/lava-server/settings.d</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">AUTH_SOCIALACCOUNT</span><span class="p">:</span> <span class="s2">&quot;{&#39;gitlab&#39;:{&#39;GITLAB_URL&#39;: &#39;https://gitlab.example.com&#39;}}&quot;</span>
</pre></div>
</div>
<p>This requires django-allauth to be installed manually (e.g., on Debian
you would install the package <code class="docutils literal notranslate"><span class="pre">python3-django-allauth</span></code>). Afterwards,
run <code class="docutils literal notranslate"><span class="pre">lava-server</span> <span class="pre">manage</span> <span class="pre">migrate</span></code>.</p>
<p>Other <a class="reference external" href="https://django-allauth.readthedocs.io/en/latest/providers.html">authentication providers</a> might require slightly different configuration
or even none at all, e.g. when working with <a class="reference external" href="https://gitlab.com">https://gitlab.com</a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">AUTH_SOCIALACCOUNT</span><span class="p">:</span> <span class="s2">&quot;{&#39;gitlab&#39;:</span><span class="si">{}</span><span class="s2">}&quot;</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>To maintain compatibility with LAVA 2021.03 - 2021.09 GitLab
authentication support can also be enabled by setting
<cite>AUTH_GITLAB_URL</cite> and <cite>AUTH_GITLAB_SCOPE</cite> directly.</p>
</div>
<p>Restart the <code class="docutils literal notranslate"><span class="pre">lava-server</span></code> and <code class="docutils literal notranslate"><span class="pre">apache2</span></code> services after any changes.</p>
<p>Before you can use external authentication provider, some additional setup steps
need to be performed (following example covers <a class="reference external" href="https://docs.gitlab.com/ce/integration/oauth_provider.html">GitLab OAuth2 authentication</a>):</p>
<ul class="simple">
<li><p>In your GitLab instance, you need to add your LAVA installation as an
<strong>Application</strong>, and enable the <code class="docutils literal notranslate"><span class="pre">read_user</span></code> scope.</p></li>
<li><p>The Redirect URI is the URL where users are sent after they authorize with
GitLab. The form is: <cite>LAVA_URL/accounts/gitlab/login/callback</cite>
Currently there seems to be a bug in GitLab so the Redirect URI works only
with <strong>http</strong> protocol.</p></li>
<li><p>After saving the application in GitLab, you will be provided with an
<strong>Application ID</strong> and a <strong>Secret</strong>.</p></li>
<li><p>In your LAVA administration dashboard, go to <strong>Social Accounts</strong> and
add a <strong>Social application</strong>. Select <strong>GitLab</strong> as provider and
enter the credentials you obtained from GitLab as <strong>Client id</strong> and
<strong>Secret key</strong>.</p></li>
<li><p>While adding the <strong>Social application</strong> make sure to move the sites
you will use GitLab to authenticate from the <strong>Available sites</strong> to
<strong>Chosen sites</strong> on the <strong>Sites</strong> tables or <code class="docutils literal notranslate"><span class="pre">allauth</span></code> will raise
an exception saying a matching query does not exist.</p></li>
</ul>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If SMTP is not set up in LAVA, you can get a 500 Internal server
error. Login will still work despite the error.</p>
</div>
</section>
<section id="using-open-id-connect-oidc-authentication-providers">
<h2>Using Open ID Connect (OIDC) authentication providers<a class="headerlink" href="#using-open-id-connect-oidc-authentication-providers" title="Permalink to this heading">¶</a></h2>
<p>LAVA server can be configured to authenticate using OIDC providers
such as Keycloack or Azure AD. The OIDC library used is
<a class="reference external" href="https://github.com/mozilla/mozilla-django-oidc">mozilla-django-oidc</a>.</p>
<p>The library does not come pre-installed and must be installed through
external means. (for example, with <code class="docutils literal notranslate"><span class="pre">pip</span></code>)</p>
<p>To enable OIDC authorization set <code class="docutils literal notranslate"><span class="pre">AUTH_OIDC</span></code> dictionary in one of the
configuration files.</p>
<p>Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">---</span>

<span class="n">AUTH_OIDC</span><span class="p">:</span>
  <span class="n">OIDC_RP_CLIENT_ID</span><span class="p">:</span> <span class="s2">&quot;1&quot;</span>
  <span class="n">OIDC_RP_CLIENT_SECRET</span><span class="p">:</span> <span class="s2">&quot;bd01adf93cfb&quot;</span>
  <span class="n">OIDC_OP_AUTHORIZATION_ENDPOINT</span><span class="p">:</span> <span class="s2">&quot;http://testprovider:8080/openid/authorize&quot;</span>
  <span class="n">OIDC_OP_TOKEN_ENDPOINT</span><span class="p">:</span> <span class="s2">&quot;http://testprovider:8080/openid/token&quot;</span>
  <span class="n">OIDC_OP_USER_ENDPOINT</span><span class="p">:</span> <span class="s2">&quot;http://testprovider:8080/openid/userinfo&quot;</span>
</pre></div>
</div>
<p>See <a class="reference external" href="https://mozilla-django-oidc.readthedocs.io/en/stable/settings.html">mozilla-django-oidc settings</a>
for the list of configuration keys.</p>
<p>One extra setting that LAVA provides is <code class="docutils literal notranslate"><span class="pre">LAVA_OIDC_ACCOUNT_NAME</span></code>
which sets the login message for OIDC login prompt. For example,
it can be set to <code class="docutils literal notranslate"><span class="pre">Azure</span> <span class="pre">AD</span> <span class="pre">account</span></code>. By default it is set to
<code class="docutils literal notranslate"><span class="pre">Open</span> <span class="pre">ID</span> <span class="pre">Connect</span> <span class="pre">account</span></code>.</p>
</section>
</section>


    </div>
      
  </div>
</div>
<footer class="footer">
  <div class="container">
    <p class="pull-right">
      <a href="#">Back to top</a>
      
    </p>
    <p>
        &copy; Copyright 2010-2019, Linaro Limited.<br/>
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 5.3.0.<br/>
    </p>
  </div>
</footer>
  </body>
</html>